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1.  Introduction 


The  United  States  Air  Force  Office  of  Scientific  Research  awarded  an  equipment  grant  to 
Florida  International  University  to  establish  a  laboratory  with  modern  workstations  to  facil¬ 
itate  research  in  the  area  of  visual  languages.  The  grant  was  awarded  on  1  November  1993 
for  a  period  of  one  year. 

The  laboratory  required  a  relatively  large  space  with  appropriate  networking  infra-structure 
in  place.  The  location  of  the  lab  was  secured  within  the  University's  ECS  (Engineering  and 
Computer  Science)  building  in  Summer  of  1994.  The  purchase  of  required  equipment  were 
completed  in  Spring  of  1995. 

The  laboratory  conducts  research  both  at  the  graduate  and  undergraduate  levels  in  the 
general  area  of  visual  languages.  The  main  focus  of  our  group  is  the  application  of  visual 
techniques  to  Parallel  Programming,  Distributed  Interactive  3D  Applications  and  Virtual 
Reality.  There  are  ongoing  research  projects  that  are  supervised  by  the  Principle  Investigator 
and  conducted  by  students.  On  the  average,  about  5  students  per  semester  have  participated. 
With  the  complete  laboratory  equipment  in  place  at  this  time,  it  is  expected  that  student 
participation  to  increase.  Most  of  the  students  participate  in  our  group  for  at  least  two 
semesters.  The  first  semester  is  utilized  to  study  the  background  literature,  learn  how  to 
use  various  software  systems  and  the  details  of  existing  projects.  Armed  with  the  knowledge 
acquired  in  their  first  semester,  the  students  spend  their  second  and  possibly  their  third 
semester  designing  and  implementing  a  software  system  appropriate  to  their  level  of  seniority. 


2.  Summary  of  ongoing  projects 

This  section  provides  a  summary  of  various  research  projects  that  are  conducted  within  the 
laboratory. 

2-1  Visualization  techniques  for  Parallel  Programming 

Parallel  computers  have  traditionally  provided  computing  power  only  to  a  limited  number 
of  (largely  scientific)  users.  With  rapid  improvements  in  hardware  technology,  however, 


1 


parallel  computers  are  no  longer  just  experimental  machines  in  the  computer 
science  labs.  The  near  future  promises  to  put  parallel  computers  on  a  desk  top 
and  make  them  available  to  the  general  public. 

If  the  tools  to  assist  parallel  programming  remain  relatively  primitive,  such  technological 
advances  may  not  be  fully  exploited  by  the  general  computing  community.  But  help  may  be 
available  from  experience  with  sequential  programming,  where  visual  languages  have  been  a 
valuable  tool  for  assisting  software  development.  The  value  of  visual  programming  languages 
and  graphical  interfaces  has  long  been  recognized  in  the  area  of  sequential  programming.  We 
claim  that  bringing  visual  programming  techniques  to  the  domain  of  parallel  programming 
will  be  equally  valuable.  Based  on  the  idea  that  pictures  can  help  both  understanding  and 
remembering,  visual  programming  research,  for  examples)  aims  at  the  design  and  imple¬ 
mentation  of  easy-to-use  programming  languages  and  tools  to  increase  the  programmer’s 
expressive  power  and  productivity. 

Visualization  research  falls  in  two  broad  categories;  processing  visual  data  (images)  and 
languages  that  allow  programming  using  visual  (graphical)  expressions.  Our  research  effort 
is  concentrated  on  the  development  of  visual  languages. 

Programming  for  parallel  machines  has  been  a  substantial  technical  problem.  If  we 
wish  to  develop  visual  programming  languages  for  parallel  machines,  we  need  a  test  bed 
for  conducting  experiments  in  language  design.  Such  experiments  might  include  changing 
the  graphical  representations  of  tasks,  program  data,  output  data,  flow  of  control  and  com¬ 
munication,  for  example.  If  we  can  rapidly  implement  such  language  design,  the  time  gap 
between  the  conception  of  new  ideas  and  their  validation  is  minimized. 

To  this  end,  our  Visual  Editor  Generator  System  aims  at  the  development  of  a  experi¬ 
mental  test  bed  for  the  development  of  visual  programming  languages. 

To  discuss  the  Generator  system,  the  design  language  Raddle  is  chosen  as  our  target 
parallel  language.  VERDI  is  a  visual  environment  that  allows  the  simulation  of  concurrent 
designs  in  Raddle.  Our  paper  describes  how  VERDI-like  interfaces  for  Raddle  can  be  speci¬ 
fied  within  the  Generator  system.  The  difference  between  VERDI  and  our  interface  is  that 
we  are  using  a  formal  framework  to  define  the  visual  interface  as  opposed  to  VERDI’s  ad-hoc 
interface  .  The  formal  approach  affords  the  language  designer  the  possibility  to  modify  the 
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set  of  allowed  editing  operations  and  change  the  shapes  and  the  placement  of  objects  in  the 
target  visual  interface  at  the  specification  level. 

2.2  Distributed  Interactive  3D  Applications 

The  ability  to  interact  with  objects  and  applications  in  a  three  dimensional  virtual  environ¬ 
ment  is  one  of  the  key  issues  to  improving  human-computer  interactions  and  hence  produc¬ 
tivity.  However,  the  large  demand  on  computational  resources  requires  the  components  of 
such  a  system  be  distributed  over  a  network  of  heterogeneous  machine  architectures. 

is  a  system  that  allows  developers  to  build  applications  with  a  three  dimen¬ 
sional  user  interface  that  run  in  a  virtual  environment  whose  components  are  managed  by 
applications  running  on  machines  dispersed  in  a  heterogenous  network.  Many  user  can  si¬ 
multaneously  participate  in  this  environment  which  allows  users  to  interact  with  the  various 
components  of  the  environment  and  with  each  other.  VRAPI  is  essentially  a  library  of  func¬ 
tions  that  developers  use  to  build  distributed  applications  with  a  VRUI  and  of  a  process  that 
implements  the  functionality  of  each  function  in  the  library  by  accepting  data  connections 
from  multiple  applications  and  by  servicing  any  requests  in  the  form  of  messages  that  are 
generated  by  calls  to  the  functions  and  that  arrive  through  the  connections. 

This  environment  contains  applications,  each  of  which  consisting  of  virtual  objects  whose 
behavior  is  controlled  by  client  applications.  The  client  applications  communicate  with  each 
other  and  with  a  nexus  process  called  the  world  server  via  the  message  passing  mechanism. 
Messages  are  sent  through  reliable  data  connections  between  the  client  applications  and  the 
world  server.  Client  applications  can  place  requests  with  the  world  server  to  modify  the 
prop6rti6S  of  v3,rious  objocts  in  tho  virtua.1  cnvironmont. 

A  key  feature  of  the  world  server  is  to  allow  applications  to  specify  that  they  must  be 
notified  whenever  certain  events  occur  in  the  virtual  world.  An  object  handled  by  a  client 
application  can  send  text  descriptions  of  various  desired  constraints  to  the  world  server.  This 
constraint  is  described  in  terms  of  the  properties  of  the  object  placing  the  constraint  and 
the  properties  of  any  other  objects.  The  world  server  will  check  this  constraint  every  time 
some  change  occurs  in  the  virtual  world  and  will  send  a  notification  message  to  the  object 
that  placed  the  constraint  that  the  constraint  has  been  satisfied.  This  constraint  checking 
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mechanism  is  flexible  enough  to  allow  applications  to  keep  a  consistent  view  of  all  objects  in 
the  world  server  database  at  a  relatively  low  demand  of  CPU  cycles  and  network  bandwidth. 
(See  Appendix  B  for  details.) 
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3.  Equipment  Acquired 


Quantity 

Equipment 

Vendor 

1. 

HP  DeskJet  1200C  Postscript  Color  Printer. 

National  Data  Products 

1. 

4  MB  simm  for  DeskJet  1200C 

National  Data  Products 

4. 

Ink  Cartridge 

'  National  Data  Products 

1. 

P5-66  Pentium  (66MHz)  PC 

Gateway  2000 

1. 

GDM-17SE1  Sony  17”  Monitor 

Megabyte  International 

2. 

LO1052  Supra  28.8  External  Modems 

National  Data  Products 

1. 

WB-W050EX  Workstation.  Indigo  2  Extreme, 

Silicon  Graphics 

32  MB,  100/50MHz,  1.0  GB  disk,  19”  Monitor 

Silicon  Graphics 

1. 

W8A1-5032  Worksation,  Indy,  100  MHz  R4600PC 

8  Bit  Color,  32MB,  535  MB  disk,  17”  Monitor 

Silicon  Graphics 

4. 

W8B1-1G32  Workstation,  Indy,  133  MHz  R4600SC 

8  Bit  Color,  32MB,  1.0  GB  disk,  17”  Monitor 

Silicon  Graphics 

1. 

PC  ZPD6934KS  Zenith  Z-Star  EX  DX2/50  MHz 
4MB,  200MB  disk,  9.5”  Monochrome  LCD 

Zenith  Data  Systems 

1. 

AC3100  Western  Digital  1  GB,  Hard  drive 

Dataflex  Corporation 

2. 

CE-VR  Crystal  Eyes  Stereoscopic  viewer 

Stereographies  Corp. 

1. 

Spaceware  IMC;  Advcd  Interaction  Dev.  Kit; 
manual,  driver,  demos,  libraries,  Spaceball 
Model2003;  Power  adapter;  Serial  Interface  Cable 

Spaceball  Technologies 

1. 

Software:  SC4-Inventor-2.0  Iris  Open  Inventor 

Silicon  Graphics 

1. 

Software:  SC4-Perf-1.2  Iris  Performer  Real-Time 
Graphics  Dev.  Environment 

Silicon  Graphics 

1. 

Software:  SC4-DMDEV-2.0  Digital  Media 

Dev.  Software  Libraries 

Silicon  Graphics 

4.  Student  Participation 

As  of  Summer  of  1995,  the  following  students  have  been  members  of  our  research  group  and 
have  utilized  the  laboratory  equipment  to  carry  out  their  work. 

•  Carry  Bakker 

•  Carlos  Flores 

•  Louis  Florit 

•  Amyn  Gilani 
o  Andre  Henry 

•  Virgiliue  Mocanu 

•  Alfredo  Rojas 
®  Johan  Sosa 

•  Cory  Tsang 

•  Kendrick  Vargas 

•  Holger  Wiechert 

®  Christopher  Wong 


Appendix  A. 


A  Test  Bed  for  Experimenting  with  Visualization  of  Parallel 

Programs 

F.  Arefi,  M.  Evangelist  and  M.  Milani 
School  of  Computer  Science 
Florida  International  University 
University  Park 
Miami,  FL  33199 
arefi@fiu.edu 


Abstract 

Because  of  the  lack  of  the  software  tools  to  as¬ 
sist  concurrent  programming,  programming  for  parallel 
computers  has  been  a  significant  technical  problem  for 
diverse  range  of  users.  We  are  concentrating  on  tech¬ 
niques  that  allow  computing  and  non- computing  ex¬ 
perts  to  define  what  they  need  and  then  automatically 
generate  the  specified  visual  language.  Consequently, 
our  visual  language  research  aims  at  the  development 
of  a  test  bed  for  conducting  experiments  in  language 
design  and  speed  up  the  implementation  process  for 
tools  to  assist  parallel  computing. 


1  Introduction 

Parallel  computers  have  traditionally  provided 
computing  power  only  to  a  limited  number  of  (largely 
scientific)  users.  With  rapid  improvements  in  hard¬ 
ware  technology,  however, 

parallel  computers  are  no  longer  just  exper¬ 
imental  machines  in  the  computer  science 
labs.  The  near  future  promises  to  put  paral¬ 
lel  computers  on  a  desk  top  and  make  them 
available  to  the  general  public  [6]. 

If  the  tools  to  assist  parallel  programming  remain 
relatively  primitive,  such  technological  advances  may 
not  be  fully  exploited  by  the  general  computing  com¬ 
munity.  But  help  may  be  available  from  experience 
with  sequential  programming,  where  visual  languages 
have  been  a  valuable  tool  for  assisting  software  devel¬ 
opment.  The  value  of  visual  programming  languages 
and  graphical  interfaces  has  long  been  recognized  in 
the  area  of  sequential  programming.  We  claim  that 


bringing  visual  programming  techniques  to  the  do¬ 
main  of  parallel  programming  will  be  equally  valuable 
[7,  3].  Based  on  the  idea  that  pictures  can  help  both 
understanding  and  remembering,  visual  programming 
research  (see  [4,  5],  for  examples)  aims  at  the  design 
and  implementation  of  easy-to-use  programming  lan¬ 
guages  and  tools  to  increase  the  programmer’s  expres¬ 
sive  power  and  productivity. 

Visualization  research  falls  in  two  broad  categories: 
processing  visual  data  (images)  and  languages  that  al¬ 
low  programming  using  visual  (graphical)  expressions. 
Our  research  effort  is  concentrated  on  the  development 
of  visual  languages. 

Programming  for  parallel  machines  has  been  a  sub¬ 
stantial  technical  problem.  If  we  wish  to  develop  visual 
programming  languages  for  parallel  machines,  we  need 
a  test  bed  for  conducting  experiments  in  language  de¬ 
sign.  Such  experiments  might  include  changing  the 
graphical  representations  of  tasks,  program  data,  out¬ 
put  data,  flow  of  control  and  communication,  for  ex¬ 
ample.  If  we  can  rapidly  implement  such  language 
design,  the  time  gap  between  the  conception  of  new 
ideas  and  their  validation  is  minimized. 

To  this  end,  our  Visual  Editor  Generator  System 
aims  at  the  development  of  a  experimental  test  bed 
for  the  development  of  visual  programming  languages. 

To  discuss  the  Generator  system,  the  design  lan¬ 
guage  Raddle  [9]  is  chosen  as  our  target  parallel  lan¬ 
guage.  VERDI  [12]  is  a  visual  environment  that  allows 
the  simulation  of  concurrent  designs  in  Raddle.  Our 
paper  describes  how  VERDI-like  interfaces  for  Raddle 
can  be  specified  within  the  Generator  system.  The  dif¬ 
ference  between  VERDI  and  our  interface  is  that  we 
are  using  a  formal  framework  to  define  the  visual  in¬ 
terface  as  opposed  to  VERDI’s  ad-hoc  interface  .  The 
formal  approach  affords  the  language  designer  the  pos¬ 
sibility  to  modify  the  set  of  allowed  editing  operations 


and  change  the  shapes  and  the  placement  of  objects 
in  the  target  visual  interface  at  the  specification  level. 


2  The  Visual  Editor  Generator 

The  Visual  Editor  Generator  System  [1,  2]  provides 
a  formal  framework  to  visually  specify  syntax-directed 
diagram  editors  and  automatically  generate  them  from 
specifications.  The  family  of  diagram  editors  that  may 
be  specified  and  generated  within  the  editor  generator 
system  are  essentially  customized  graph  editors  that 
share  common  structures  and  functionalities.  A  graph 
editor  might  be  customized  in  two  primary  ways.  Cus¬ 
tomizing  the  physical  appearance  of  the  graphs  being 
manipulated  involves  declaring  diflferent  node  shapes 
and  colors,  edge  shapes  and  colors  and  the  geometric 
relationships  among  them.  The  set  of  possible  graph 
manipulations  (editing  operations)  are  customized  by 
providing  a  collection  of  graph  transformation  rules 
that  allow  or  disallow  editing  operations  in  certain 
contexts. 

The  editor  generator  system  allows  generating  ed¬ 
itors  that  are  customizable  in  both  the  physical  ap¬ 
pearance  of  graphs  and  the  editing  operations  that  are 
allowed.  Customizability  of  the  physical  appearance  is 
addressed  by  providing  general  SmallTalk  classes  for 
graph  nodes  and  edges  that  might  be  specialized  (in¬ 
herited  from)  to  capture  the  application  specific  be¬ 
havior  of  various  node  and  edge  types.  Within  the 
framework  of  such  customizations  one  would  special¬ 
ize  the  general  node  and  edge  classes  to  specific  sub¬ 
classes  that  contain  information  regarding  the  desired 
shape,  color,  and  so  on.  This  is  similar  to  Edge  [11] 
which  facilitates  graph  editor  customization  by  provid- 
ing  general  C-I-+  node  and  edge  classes.  The  graph 
editing  operations  are  customized  by  describing  the 
allowable  context-dependent  graph  editing  operations 
using  a  starting  graph  and  a  collection  of  specialized 
graph  transformation  rules  [1]. 

A  customized  editor  designer  develops  a  specialized 
graph  editor  by  providing  the  generator  system  the 
specification  of  the  needed  editor.  This  specification 
contains  the  description  of  both  the  desired  physical 
appearance  and  graph  manipulations.  The  generator 
supports  the  development  of  both  parts  of  the  specifi¬ 
cation  by  providing  appropriate  tools.  The  Generator 
system  provides  the  editor  designer  with  four  editors. 
The  Set  Editor  allows  the  declaration  of  the  labels 
of  nodes  and  edges  of  the  underlying  graph  transfor¬ 
mation  system.  The  Graph  Editor  provides  facilities 
to  develop  and  specify  the  target  editor’s  underlying 


starting  graph  and  transformation  rules.  The  Im¬ 
age  Editor  allows  the  development  of  icons  associated 
with  various  node,  edge  and  rule  types.  The  Relation 
Editor  is  used  to  specify  the  geometric  relationships 
among  node  types.  Once  the  specification  of  the  tar¬ 
get  editor  is  complete,  the  generator  system  automat¬ 
ically  produces  the  target  editor.  Figure  1  depicts  an 
overall  view  of  the  generator  system. 

The  visual  language  specification  is  a  form  of  graph 
grammar  that  is  customized  for  the  specification  of 
syntax-directed  visual  editors.  Graph  grammars  are 
two  dimensional  in  nature,  are  inherently  concurrent, 
and  allow  for  the  dynamic  creation  and  deletion  of 
nodes  and  arcs,  and,  therefore,  are  suitable  for  the 
specification  of  visual  parallel  programming  languages 
[8,  10]. 


3  Formal  Specification  of  Visual  Lan¬ 
guages 

In  [1]  we  introduced  a  unified  framework  to  specify 
visual  languages  and  their  permitted  manipulations. 
This  framework  allows  languages  be  defined  as  one 
initial  object  and  a  collection  of  editing  operations. 
This  way,  any  object  that  can  be  obtained  by  apply¬ 
ing  a  sequence  of  allowed  editing  operations  to  the 
initial  object  is  defined  to  be  a  program  in  the  lan¬ 
guage  being  specified.  That  is,  languages  are  defined 
as  dynamic  objects  that,  as  the  result  of  applying  edit¬ 
ing  operations,  change  from  one  form  to  another  with 
each  form  being  a  member  of  the  language. 

3.1  Graph  Transformation  System 

The  Visual  Editor  Generator’s  underlying  specifica¬ 
tion  framework  is  a  graph  transformation  system[l].  A 
Graph  Transformation  System  is  a  5-tuple 

T=^<Lv,Le,S,EO,M> 

where 

•  Ly  and  Le  are  sets  of  symbols  called  the  node 
label  set  and  the  edge  label  set,  respectively, 

•  S,  the  starting  graph,  is  a  labeled  directed  graph 
over  <  Ly,Le  >, 

»  EO  is  a  collection  of  editing  operation  labels  and 

•  M  is  a  collection  of  graph  transformation  rules. 

A  graph  transformation  system  defines  a  graphi¬ 
cal  language  and  its  syntax  directed  editor.  It  has  an 


Figure  1:  The  Generator  System 


internal  memory  that  is  organized  as  a  graph  which 
initially  contains  the  starting  graph.  Once  a  graph  is 
in  the  internal  memory,  the  graph  transformation  sys¬ 
tem  repeatedly  applies  its  transformation  rules  until 
no  rule  can  be  applied. 

To  discuss  the  specification  language  as  well  as  the 
Generator  system,  the  design  language  Raddle  [9]  is 
chosen  as  our  target  parallel  language. 

4  Raddle  a  Design  Language 

Raddle  is  a  robust  linguistic  tool  suitable  for  design¬ 
ing  large,  concurrent  software  systems.  Raddle  per¬ 
mits  the  designer  to  develop  a  large  software  system  at 
a  high  level  of  abstraction  by  partitioning  the  system 
into  “teams”  of  asynchronous  processes  that  coordi¬ 
nate  and  communicate  with  each  other.  The  designer 
can  then  decompose  the  interactions  into  equivalent 
and  smaller  interactions.  (See  [9]  for  more  details.) 

4.1  Concepts  and  Abstraction 

VERDI  [12]  is  a  visual  environment  that  allows  the 
simulation  of  concurrent  designs  in  Raddle.  This  sec¬ 
tion  provides  an  overview  of  the  underlying  concepts 
for  VERB  I- like  interface. 

4.1.1  The  Primitive  Actions 

A  VERDI  interface  is  designed  from  five  primitive  ac¬ 
tions,  Figure  2  depicts  the  icons. 


Figure  2:  The  Primitives 

•  Code-block:  is  a  set  of  assignment  statements. 

•  Parallel:  consists  of  a  set  of  statements  that  are 
executed  in  parallel. 

•  Interaction:  is  the  synchronization  and  commu¬ 
nication  mechanism. 

•  Cast:  transfers  control  to  procedures. 

•  Return:  passes  control  to  the  point  that  the  pro¬ 
cedure  was  invoked. 


4.1.2  Control  Flow 

There  are  three  control  constructs: 

•  Choice:  selection  of  one  of  the  several  actions. 

•  Sequence:  execution  of  actions  sequentially  left  to 
right. 

•  Iterator:  iteration  of  several  actions. 

4.1.3  Parallel  Activities 

A  Team  consists  of  set  of  communicating  Roles,  which 
may  be  either  Processes  or  Procedures,  Synchroniza¬ 
tion  and  communication  among  the  roles  in  a  team  is 
accomplished  by  n-parity  interaction.  (See  [9]  and  [12] 
for  complete  and  detailed  information.) 


5  The  Specification  of  VERDI-like  lan¬ 
guage 

The  specification  of  VERDI-like  interface  consists 
of  description  of  both  the  visual  appearance  and  graph 
manipulations.  The  generator  system  supports  the  de¬ 
velopment  of  both  parts  of  the  specification  by  provid- 
ing  appropriate  tools. 

•  Stepl:  defining  the  nodes  and  edge  labels. 

-  Node  labels:  Verdi,  Team,  Role,  Proc(for 
process),  Prod(for  procedure)  Action,  End, 
Body  (for  the  body  of  a  proc  or  prod),  Sel- 
body(for  the  expanding  to  more  choices), 
Codeblock,  Parallel,  Interaction,  Cast,  Re¬ 
turn  and  Lambda  (for  defining  constraints). 

-  Editing  operation  labels:  Mycursor  (for 
cursor  position),  Start,  Addteam,  Addtea- 
mafter,  Addrole,  Addroleafter,  Addprocess, 
Addprocedure,  delete  and  etc. 

—  Edge  labels:  Apply,  Nteam  (link  between 
teams),  Bteam  (for  going  back  to  previous 
team,  we  use  this  kind  of  edge  for  geomet¬ 
ric  attribute  evaluation),  Nrole,  Brole,  Ctf 
(control  flow),  Bctf  (backward  control  flow), 
Itr  (iteration),  Cff  (control  flow  false),  Bcff 
and  etc. 

The  language  designer  uses  the  Set  editor,  Image 
editor  and  the  Relation  editors  to  specify  the  la¬ 
bels  of  the  nodes  and  edges,  to  develop  the  shapes 
associated  with  each  node  and  edge,  and  also  to 
specify  the  geometric  relationship  among  nodes 
respectively. 


•  Step2:  defining  the  start  graph. 

Start  graph  is  the  smallest  meaningful  program 
in  the  language.  Figure  3  depicts  the  start  graph 
for  VERDI-like  interface. 


iiiilii 

Verdi 

Figure  3:  The  start  graph 


•  Step3:  defining  the  transformation  rules  for  the 
language. 

The  transformation  rules  are  functions  that  can 
be  applied  to  graph  and  modify  it  accordingly. 
Figures  4  and  5  depicts  the  left  hand  side  and  a 
right  hand  side  of  a  graph  transformation  rule, 
respectively. 

The  language  designer  uses  the  generator’s  Graph 
editor  to  specify  the  start  graph  and  the  transforma¬ 
tion  rules. 

5.1  An  Example  of  Applying  a  Transfor¬ 
mation  Rule  to  a  Graph 

Figures  4  and  5  depict  a  graph  transformation  rule 
for  expanding  a  node  named  Body  to  iteration  con¬ 
struct  Figure  4  is  the  left  side  of  the  rule  and  it  models 
a  graph  that  this  rule  can  be  applied  to.  The  condi¬ 
tion  here  is  that  the  cursor  should  highlight  a  node 
named  Body  and  the  Body  should  have  an  incoming 
edge  labeled  Ctf  from  a  node  (it  can  be  any  node)  and 
it  should  have  an  outgoing  edge  labeled  Bctf  to  the 
same  node.  Also  Body  should  have  an  outgoing  edge 
labeled  Ctf  to  a  node  and  should  have  an  incoming 
edge  labeled  Bctf  from  the  same  node.  If  there  is  a 
match  between  the  left  rule  and  the  graph  then  the 
transformation  rule  is  applicable  to  the  graph.  The 
following  steps  are  taken  for  applying  a  transforma¬ 
tion  rule  to  a  graph. 

•  Delete  all  the  left  hand  side’s  pattern  nodes  (rect¬ 
angular  shaped  nodes)  from  the  graph.  In  our 


Figure  4:  The  left  side  of  a  transformation  rule  for  add  iteration 


Figure  5:  The  right  side  of  a  transformation  rule  for  add  iteration 


example  the  nodes  Additr  and  Body  get  deleted 
from  the  graph. 

•  Add  all  the  right  hand  side’s  pattern  nodes  (rect¬ 
angular  shaped  nodes)  to  the  graph  and  then  add 
the  new  edges.  In  our  example  Action,  Body,  Ac¬ 
tion,  Body  and  corresponding  edges  get  added  to 
the  graph. 

•  Highlight  the  node  being  pointed  at  by  Mycursor. 

o  Find  all  the  applicable  rules  for  the  highlighted 
node  and  display  those  in  the  menu  area. 

Figure  6  shows  the  VERDI-like  language  before  ap¬ 
plying  the  Additr  command.  Figure  7  depicts  the  the 
language  after  application  of  the  command. 


new  ideas  through  see  and  feel  process.  They  can  eas¬ 
ily  change  the  functionality  and  physical  appearance 
of  their  language  and  get  the  immediate  feedback  by 
using  one  of  the  generator’s  tools  and  consequently  the 
implementation  effort  for  parallel  computation  tools  is 
reduced.  Using  our  tool,  we  have  been  able  to  generate 
the  VERDI-like  interface  in  a  few  week. 


6  The  Generation  of  VERDI-like  In¬ 
terface  (language) 

Appendix  A  depicts  some  of  the  rules  for  VERDI- 
like  language.  After  the  specification  of  all  the  nodes 
and  edges  and  transformation  rules,  the  Generator 
Accepts  all  the  information  and  generates  the  Visual 
Syntax-directed  editor  for  the  target  language.  Fig¬ 
ure  8  shows  the  visual  syntax-directed  editor  interface 
for  VERDI-like  language.  Figures  8  and  9  depict  the 
high  level  design  of  an  electronic  funds  transfer  sys¬ 
tem.  Because  of  the  limitation  of  the  screen  space  the 
last  team  of  eft-System  has  been  shown  in  Figure  9. 
(For  more  detail  [12]). 


7  Conclusion 

In  this  paper  we  explained  the  specification  and  the 
generation  of  the  VERDI-like  language  and  its  inter¬ 
face.  The  difference  between  VERDI  and  our  inter¬ 
face  is  that  we  are  using  a  formal  framework  to  de¬ 
fine  the  visual  interface  as  opposed  to  VERDI’s  ad-hoc 
interface.  The  formal  approach  affords  the  language 
designer  the  possibility  to  modify  the  set  of  allowed 
editing  operations  and  to  change  the  shapes  and  the 
placement  of  objects  in  the  target  visual  interface  at 
the  specification  level.  The  Generator  system  provides 
user  friendly  tools  that  could  be  used  during  and  af¬ 
ter  the  generation  of  any  new  visual  language.  These 
tools  will  help  the  language  designer  to  develop  their 


Figure  6:  The  screen  before  applying  Additr 


Figure  7:  The  screen  after  applying  Additr 
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Appendix  B. 


VRAPI  is  a  programming  library  used  for  developing  applications  that  run  on 
different  machines  on  a  network  and  that  have  a  Virtual  Reality  user  interface.  A  set  of 
applications  running  together  constitute  a  virtual  environment  that  can  be  shared  by 
more  than  one  user  at  the  same  time.  Through  this  environment,  users  can  interract 
with  each  other  through  the  use  of  applications  developed  with  VRAPI  such  as  a  virtual 
telephone  or  virtual  bodies,  etc. 

VRAPI  is  a  set  of  functions  written  in  C.  The  Reference  Manual  describes  the 
functionality  and  syntax  of  these  function  calls.  The  Reference  Manual  also  tells  the 
developer  if  the  functions  are  blocking  or  non-blocking  since  the  applications  written 
with  these  function  calls  are  supposed  to  function  in  a  distribuited  shared  environment 
and  preferably  have  real-time  response. 


The  system  consists  of  three  general  groups  of  components.  The  first  group  is 
the  set  of  clients  or  applications.  Examples  of  these  applications  are  a  virtual  terminal 
for  running  a  shell,  an  virtual  airplane  for  flight  simulation,  a  CAD  application  for 
engineers,  etc.  These  clients  are  separate  processes  running  on  arbitrary  machines  on 
a  network.  The  clients  manage  virtual  objects.  A  set  of  virtual  objects  managed  by  one 
or  rnore  clients  work  together  to  form  an  application.  For  example,  a  virtual  airplane 
apphcation  might  consist  of  the  wings,  fuselage,  tail,  landing  ghear,  control  pannei,  etc. 
All  these  objects  can  be  controlled  by  one  single  client  or  if  the  developer  chooses  to 
really  modularize  things,  he  may  want  to  program  one  client  that  implements  the 
behavior  of  the  objects  that  make  up  the  body  of  the  airplane  (wings,  tail,  fuselage)  and 
a  different  client  that  implements  the  behavior  of  the  control  pannei  and  instruments  of 
the  airplane.  These  two  cseparate  clients  may  communicate  with  each  other  via 

passing  by  using  the  ICCM  (Inter  Client  Communication  Mechanism)  feature 

It  is  important  to  understand  the  distinction  between  the  client  and  the  object.  A 
client  IS  a  process  that  runs  on  some  machine  on  the  network.  It  contains  code  that 
causes  some  virtual  object  in  the  VR  world  to  change  its  properties  such  as  position 
ro  ation,  shape,  etc.  A  client  is  like  a  pupeteer  controlling  the  virtual  objects.  A  client 
may  manage  more  than  one  object  so  the  client  may  contain  code  that  implements  the 
behavior  of  more  than  one  object  or  even  more  than  one  kind  (class)  of  object.  For 
example  an  application  simulating  the  furniture  inside  a  virtual  house  may  manage  a 
cocktail  fable,  a  couch,  and  two  chairs.  These  4  objects  are  examples  of  3  different 
classes  of  objects:  1  of  class  table,  1  of  class  couch,  and  2  of  class  chair. 

t  component  in  the  system  is  the  world  server.  This  is  a  single  process 

that  stores  information  about  ail  objects  in  the  virtual  world.  This  is  basically  a 
database  to  which  clients  connect  and  of  which  they  make  requests  to  modify  the 
objects  in  the  world.  For  example  clients  may  connect  to  the  world  server,  may  request 
the  creation  of  some  buildings,  a  floor,  some  trees,  etc.  Other  clients  may  request  the 
creation  of  some  cars  and  later  may  periodically  request  the  movement  of  the  cars 


The  last  general  group  of  components  that  make  up  the  system  are  the  display 
clients.  These  are  processes  that  also  connect  to  the  world  server  and  are  updated  by 
the  world  server  with  the  location,  shape,  etc,  of  every  object  in  the  world.  The  display 
clients  then  render  a  scene  of  these  objects  as  seen  from  some  point  of  view  (usually 
the  users  location).  Obviously,  every  user  must  run  at  least  one  display  client  in  order 
to  get  feedback  from  the  virtual  world.  The  display  clients  or  some  other  processes  in 
the  same  group  as  the  display  clients  read  input  from  some  input  device  such  as  a 
mouse  or  Spaceball  and  change  the  user’s  location  and  orientation  in  the  virtual  world. 


Figure  1  shows  how  the  three  types  of  components  are  linked  to  each  other  and 
how  they  communicate.  Basically,  all  communication  is  done  with  or  through  the  world 
server. 


Architecture  of  a  Client 


The  structure  of  a  client  is  somewhat  different  than  the  structure  of  a  regular 
program  that  is  running  independent  of  any  other  program  (i.e.  a  sort  routine  that  takes 
data,  processes  it,  and  outputs  it,  and  finally  exits).  A  client  written  with  VRAPI  is  an 
application  that  responds  to  events  and  messages  comming  from  other  applications  or 
from  the  world  server.  Thus  clients  are  passive  programs  that  are  dormant  when  no 
messages  are  present  and  only  process  whenever  something  “interesting”  happens 
and  the  world  server  tells  them  about  it. 

As  we  mentioned  in  the  previous  section,  the  client  contains  code  that  handles 
the  behavior  of  an  object,  multiple,  objects,  and  multiple  classes  of  objects.  This  code 
resides  inside  the  body  of  different  functions. 

Figure  2  shows  a  graphical  representation  of 
a  client’s  control  flow.  VRAPI  contains  functions  for 
the  first  two  steps  in  this  diagram.  Naturally,  the 
user  must  provide  code  for  the  functions  in  steps  3, 

4,  and  5.  These  functions  implement  the  behavior 
of  different  classes  of  objects.  They  determine  what 
kind  of  message  they  are  handling  (usually  with  a 
“switch”  statement)  and  then  send  messages  back 
to  the  world  server  requesting  that  the  objects 
behave  in  a  certan  way  such  as  move,  rotate,  scale, 
change  shape,  etc. 

So  far  we  have  shown  how  clients  receive 
messages,  dispatch  them  to  the  right  functions,  and  process  them  inside  the  functions. 
We  now  need  to  know  how  the  whole  structure  of 
the  client  looks  and  we  need  a  more  detailed 
description  of  each  step. 

In  step  0,  the  client  initializes  any  global 
variables  and  creates  the  objects  by  calling  the 
“CreateObject”  function  provided  by  VRAPI.  The 
function  “CreateObject”  asks  for  the  function 
address  that  implements  the  behavior  of  the  object 
(supplied  by  you)  as  well  as  the  object  class 
number  returned  by  “RegisterClass.”  The  function 
“CreateObject”  returns  an  object  number  that  is 
unique  in  the  virtual  world.  “CreateObject”  stores 
this  number  in  a  database  and  associates  it  with  the 
function  address. 

Step  1  is  a  call  to  “ReadMessage”  provided 
by  VRAPI  which  blocks  until  a  message  is  available  from  the  world  server  and  which 
returns  a  pointer  to  a  message  structure.  This  message  structure  contains  all  the 
necessary  information  for  the  processing  of  the  message.  This  information  includes  the 
object  number  that  should  receive  the  message. 


Figure  3  -  Structure  of  a  client 


Figure  2  -  Structure  of  a  client 


Step  2  is  a  call  to  “DispatchMessage”  which  takes  as  input  the  pointer  to  the 
message  structure  and  calls  the  function  supplied  by  you  which  implements  the 
behavior  of  the  object.  This  is  done  by  looking  up  the  object  number  (present  in  the 
message  structure)  in  the  database  and  retreiving  the  function  number  (which  was 
stored  when  you  called  “CreateObject”). 

Steps  3  to  5  are  functions  supplied  by  the  developer.  These  functions  are  celled 
with  several  parameters.  One  of  them  is  the  pointer  to  the  message  structure  returned 
by  ReadMessage.  The  other  parameters  are  redundant  information  already  present 
in  the  message  structure. 

The  body  of  a  function  that  implements  the  behavior  of  an  object  usually  consists 
of  a  “switch”  statement  that  looks  at  the  message  structure  and  determines  what  kind  of 
message  was  received  by  an  object.  You  can  then  determine  which  object  received  the 
message  by  also  looking  inside  the  structure.  This  way  different  objects  (of  the  same 
class)  can  behave  differently. 


The  object  behavior  function  defines  the  behavior  of  a  certain  class  of  objects.  It 
IS  called  by  VRAPI  whenever  a  client  receives  a  message  for  the  object  associated  with 
that  object  behavior  function.  The  association  is  made  when  calling  “CreateObject.” 
The  object  behavior  object  is  called  from  within  the  “DispatchMessage”  function. 

Strictly  speaking,  the  object  behavior  function  handles  messages  before  they  are 
server.  This  means  that  whenever  an  object  is  sent  a  message  such  as  the 
lvlOVE_OBJECT  message  which  specifies  the  new  location  of  an  object  in  3D,  the 
client  responsible  for  that  object  receives  the  message,  then  dispatches  it  to  the  object 
behavior  function.  The  object  behavior  function  then  decides  what  to  do  with  this 
message.  It  can  either  call  the  function  “DefaultServerAction”  which  basically  sends 
the  message  back  to  the  world  server  in  which  case  the  world  server  implements  the 
moving  of  the  object  by  changing  that  object’s  (x,  y,  z)  coordinates  in  its  world 
database.  Alternatively,  the  object  behavior  function  can  choose  to  ignore  the 

MOVE_OBJECT  message  or  perhaps  take  a  different  action  altogether  by  callina 
RotateObject”  or  such.  =  /  a 

Figure  4  shows  sample  code 
for  an  object  behavior  function.  This 
function  is  called  from  within 
“DispatchMessage”  with  3 
parameters.  The  first  is  a  pointer  to  a 
data  structure  containing  information 
about  the  current  connection  between 
the  client  and  the  world  server.  The 
second  is  the  object  number  that  the 
message  is  for.  The  third  is  a  pointer 
to  the  message  structure  (which 
redundantly  contains  the  object 
number  as  one  of  its  fields). 

The  body  of  the  function  is 
simple:  First  figure  out  which 


message  IS  being  handled  and  take  appropriate  action.  Next  call  “DefaultServerAction” 
to  send  the  message  back  to  the  world  server  and  let  it  take  the  appropriate  action.  In 
IS  examp  e  the  function  “DefaultServerAction”  is  called  in  all  situations.  You  may 
want  to  call  DefaultServerAction”  only  for  some  messages  while  for  others  the 
message  should  just  be  “swallowed”  by  your  function. 


To  sumarize  the  message  passing  scheme,  Figures  5-8  show  the  steps  that  are 
taken  behind  the  scenes  between  the  time  that  a  client  calls  the  function  “MoveObject” 

' . .  '  '  and  the  time  that  the  object  is  actually  moved. 

A  small  axception  occurs  when  a  client  calls  “MoveObject”  to 
move  its  own  object.  In  this  situation,  the  client  automatically  sends 

the  message  dirrectly  to  itself  instead  of 
going  through  the  world 
server. 


Figure  5 


The  world  server 
receives  the 
MOVE_OBJECT 
message  sent  by  the 
DefaultServerActton 
lunction  and  moves  the 
object  in  its  world 
database. 
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Figure  8 


Object  Shape  Formats 


Virtual  objects  have  various  characteristics.  An  object  has  fundamental 
characteristics  such  as  position,  orientation,  scale,  etc.  Similarly,  an  object  has  visual 
characteristics  such  as  shape,  color,  texture,  transparency,  luminosity,  etc.  These 
characteristics  are  stored  in  the  server  by  the  clients  that  create  the  objects.  Later, 
when  the  objects  need  to  be  displayed  by  some  user’s  viewer  application,  the  object 
shape  is  downloaded  from  the  server  by  calling  “GetShape”  and  is  rendered  by  the 
viewer. 

The  shape  of  an  object  can  be  specified  in  many  ways.  Among  the  most 
commonly  used  formats  for  specifying  3D  object  shapes  are  DXF,  3DS,  etc.  VRAPI 
does  not  place  any  constraint  on  the  object  shape  but  leaves  this  decision  up  to  the 
implementor  of  the  viewer  application.  VRAPI  allows  this  flexibility  by  permiting  the 
application  to  register  the  shape  description  for  an  object  in  more  than  one  format.  For 
example,  an  application  creating  a  cube  can  call  “DefineShape”  or 

“DefineShapeFromFile”  with  different  format  names  and  different  format  bodies  as  their 
parameters. 

I  DefineShapeFromFile (pConnection,  hCube,  "VOF",  "cube.vof");  | 

and 

I  DefineShapeFromFile(pConnection,  hCube,  "DXF",  "cube.dxf");  [ 

This  way  two  distinct  descriptions  for  the  same  object  are  stored  in  the  world  server. 
One  description  is  in  the  VOF  format  while  the  other  is  in  the  DXF  format.  Later  a 
viewer  application  can  call  “GetShapeFormat”  to  enumerate  all  available  formats  and 
once  it  finds  a  format  that  it  can  interpret,  it  can  call  “GetShape”  to  download  the 
description  in  that  particular  format. 

This  mechanism  allows  clients  to  specify  the  shape  of  an  object  in  various 
degrees  of  detail  complexity.  The  viewer  application  can  then  download  only  the 
format  that  it  can  actually  render  in  real  time. 


A  Simple  Application 


In  this  section  we  will  see  a  sample  application  that  loads  an  object  from  a  file 
and  creates  it  in  the  world.  The  following  listing  shows  the  code: 


ctibe.c 


cube.c  -  an  application  that  connects  to  the  server 

loads  the  object  in  file  'cube.vof'  and  does 
nothing  else 


#include  <stdio.h> 

#include  <vrlib.h> 

HOBJECT  hObjl,  hLast; 

void  RegisterShapefPCONNECTION,  HOBJECT,  char  *,  char  *); 
void  fnObjFunctionl (PCONNECTION,  HOBJECT,  PMESSAGE) ; 

/****************************^******^^^^^^^^^^^^^^^^^^^^^^^^ 
void  usage_error ( )  { 
fprintf (stderr, 

"Usage;  cube  ma chine \n "} ; 

exitil) ; 

} 

/***********1r******i,1,1,**r*1,1,1,*!it**-i,*i,i,ir**-l,*i,-k**1,*t,****i,i,**i,*iti,. 

main tint  argc,  char  **argv)  { 

PCONNECTION  pConnection; 
char  server_hostnameI100] ; 

PMESSAGE  pMsg; 

HCLASS  hClassl; 

if (argc  <  2)  { 
usage_error { ) ; 

} 

strcpy(server_hostnaine,  argv[l]); 

pConnection  =  ConnectToServer  (server_hostnaine) ; 
if (pConnection  ==  (PCONNECTION)  -1)  { 
fprintf (stderr, 

"Could  not  connect  to  server  on  machine  %s\n", 
server_hostname) ; 

exit (1) ; 

) 

else  ( 

printf( "Connection  made  OK\n"); 

) 

hClassl  =  RegisterClass (pConnection,  "TestClass" } ; 

hObjl  s  CreateObject (pConnection,  hClassl,  NULL, 
f nOb j  Func  t ionl , 

0,  100,  0,  0,  0,  0); 

print f ( ‘Sending  object  shape . . . \n“ ) ; 

DefineShapeFromFilefpConnection,  hObjl,  "VOP",  "cube .vof * ) ; 
printf{*Done  sending  object  shape ... \n" ) ; 

while (pMsg  =  ReadMessage (pConnection) )  ( 

DispatchMessage (pConnection,  pMsg) ; 

DisconnectFromServer (pConnection) ; 

) 

/*****************1l*^*******f,**i(*1r*t****i,t**i(*i,*1,1tiHt1,iH,tr*1,lel,i, 

void  fnObjFunctionl (PCONNECTION  pConn,  HOBJECT  hObj, 

PMESSAGE  pMsg)  { 

This  function  is  just  a  pass-through  function  that 
defaults  every  message  hack  to  the  world  server. 


DefaultServerAction(pConn,  pMsg) ; 


cube.vof 

OBJECT 

TRIANGLE  <0.000000  -0.000000  0.000000>  <10.000000  -0,000001 
0.000000>  <10.000000  -0.000001  10.000000> 

COLOR  <1.000000  1.000000  1.000000> 

ENDOBJECT 

OBJECT 

TRIANGLE  <0.000000  -0.000000  0.000000>  <10.000000  -0.000001 
10.000000>  <0.000000  -0.000001  10.000000> 

COLOR  <1.000000  1.000000  1.000000> 

ENDOBJECT 

OBJECT 

TRIANGLE  <0.000000  -0.000000  0,000000>  <0.000000  -0.000001 
10.000000>  <0.000000  10.784311  10.000000> 

COLOR  <1.000000  1.000000  1.000000> 

ENDOBJECT 

OBJECT 

TRIANGLE  <0.000000  -0.000000  0.000000>  <0.000000  10.784311 

10.000000>  <0.000000  10.784313  -0.000000> 

COLOR  <1.000000  1.000000  1.000000> 

ENDOBJECT 

OBJECT 

TRIANGLE  <0.000000  -0.000001  10.000000>  <10.000000  -0.000001 
10.000000>  <10.000000  10.784311  10 . 000000> 

COLOR  <1.000000  1.000000  1.000000> 

ENDOBJECT 

OBJECT 

TRIANGLE  <0.000000  -0.000001  10.000000>  <10.000000  10.784311 

10.000000>  <0.000000  10.784311  10.000000> 

COLOR  <1.000000  1.000000  1.000000> 

ENDOBJECT 

OBJECT 

TRIANGLE  <10.000000  -0.000001  10.000000>  <10.000000  -0.000001 
0.000000>  <10,000000  10.784312  -0.000000> 

COLOR  <1.000000  1.000000  1.000000> 

ENDOBJECT 

OBJECT 

TRIANGLE  <10.000000  -0.000001  10,000000>  <10.000000  10.784312 
-0.000000>  <10,000000  10.784311  10.000000> 

COLOR  <1.000000  1.000000  1.000000> 

ENDOBJECT 

OBJECT 

TRIANGLE  <10.000000  -0.000001  0.000000>  <0.000000  -0.000000 
0.000000>  <0.000000  10.784313  -0.000000> 

COLOR  <1,000000  1.000000  1.000000> 

ENDOBJECT 

OBJECT 

TRIANGLE  <10.000000  -0.000001  0.000000>  <0.000000  10.784313  - 
0.000000>  <10.000000  10.784312  -0.000000> 

COLOR  <1.000000  1.000000  1.000000> 

ENDOBJECT 

OBJECT 

TRIANGLE  <10,000000  10.784311  10.000000>  <10.000000  10.784312 
-0.000000>  <0.000000  10.784313  -0.000000> 

COLOR  <1.000000  1.000000  1.000000> 

ENDOBJECT 

OBJECT 

TRIANGLE  <0.000000  10.784311  10.000000>  <10.000000  10.784311  ; 
10.000000>  <0.000000  10.784313  -0.000000> 

COLOR  <1.000000  1.000000  1,000000>  j 

ENDOBJECT 


The  main  program  of  ciient.c  is  just  an  initialization  section  followed  by  the 
infinite  loop  that  reads  messages  from  the  queue  and  dispatches  them  to  the  object 
behavior  function.  The  object  behavior  function  does  not  do  anything  special.  It  does 


not  handle  any  messages  but  simply  passes  them  on  to  the  world  server  to  be  handled 
in  a  default  manner. 

The  listing  of  cube.vof  shows  the  definition  of  the  shape  of  the  object  being 
displayed.  The  cube  is  made  up  of  12  triangles  (two  per  face).  The  color  of  every 
triangle  is  white  (RGB  of  1 , 1 ,1).  The  object  shape  definition  is  given  to  the  server  with 
the  function  “DefineShapeFromFile”  which  simply  reads  the  file  and  sends  the  format  to 
the  world  server.  This  way,  any  display  client  can  download  the  shape  in  order  to 
render  an  image  of  the  object. 

Because  the  object  behavior  function  does  not  do  anything  special,  the  object 
can  be  moved,  rotated,  etc.  by  any  other  application.  For  example,  the  users  of  the  VR 
environment  may  be  running  clients  that  allow  them  to  grab  objects  and  move  them 
around.  When  the  object  is  sent  a  MOVE_OBJECT  or  ROTATE_OBJECT  message  by 
these  clients,  it  simply  passes  them  on  to  the  server  which  then  moves  or  rotates  the 
object. 

The  client  is  run  in  the  following  way;  Assume  you  have  a  world  server  running 
on  some  machine  called  frontier  and  a  display  client  which  is  connected  to  the  world 
server  on  frontier.  In  order  to  run  the  application,  compile  it 

%  cc  -o  cube  cube.c  -Ivr  -Uibrary_path  -\include_path 
and  run  it 

%  cube  frontier 


The  VRAPI  world  server  is  equiped  with  an  automatic  constraint  checking 
mechanism  that  checks  if  certain  constraints  registered  by  clients  have  been  met  every 
time  something  in  the  system  changes  and  if  the  constraints  are  met,  then  the  client 
that  registered  the  constraints  is  notified  with  a  message. 

Constraint  checking  by  the  world  server  simplies  the  design  of  the  clients  and 
reduces  their  computational  load.  For  example,  when  implementing  a  push  button  for 
some  VRUI  (Virtual  Reality  User  Interface),  the  button  object  “wants  to  know”  when 
some  user  pointer  is  touching  it  so  that  it  might  perform  some  action  like  change 
position  and  notify  the  application  to  which  it  beiongs. 

In  order  to  do  something  like  this,  the  client  managing  the  button  would  have  to 
send  to  the  world  server  the  constraint  specifications.  When  the  user  pointer  moves 
close  to  the  button,  the  constraint  would  be  satisfied  which  would  cause  the  world 
server  to  send  a  message  to  the  object  behavior  function  of  the  button  object. 

In  order  to  register  the  constraint,  the  client  would  call  “DefineConstarint”  with 
the  handle  of  the  button,  the  value  of  the  event  that  the  world  server  will  send  to  the 
object  when  the  constraint  is  satisfied,  and  the  ASCII  text  specifying  the  constraint. 

This  specification  would  look  something  like  this: _ 

1  distance  =  ( {other_absolute_x  -  current_absolute_x) ''2  + 

2  (other_absolute_y  -  current„absolute_y) ''2  + 

3  (other_absolute_2  -  current_absolute_2) ''2 ) (0 . 5) 

4  g  (distance  <  10)  &&  (othgr_class  ==  2) _ 

The  first  3  lines  calcu  ate  the  distance  between  the  button  object  (current  object)  and 
any  other  generic  object  (other  object).  Line  4  begins  with  the  character  which 
indicates  a  constraint.  This  line  checks  if  the  generic  object  is  within  10  units  of  the 
button  object  and  if  the  generic  object  is  of  class  ‘user  pointer’  which  is  predefined  as 
value  2. 

Constraints  can  be  formulated  in  terms  of  any  object  characteristic.  Each  object 
characteristic  has  a  value  which  can  be  accessed  by  the  constraint  definition  through 
variable  names.  A  complete  list  of  all  the  variable  names  can  be  found  in  Appendix  A. 

When  the  world  server  checks  a  particular  constraint  and  determines  that  the 
constraint  has  been  satisfied,  the  world  server  sends  a  message  to  the  object  behavior 
function  of  the  object  that  placed  the  constraint.  The  message  value  is  the  one 
specified  when  the  constraint  was  defined  and  the  message  body  contains  details 
about  the  other  (generic)  object  that  caused  the  constraint  to  be  satisfied.  This 
information  includes  things  such  as  the  other  object’s  class,  handle,  position, 
orientation,  scaling,  etc.  Appendix  A  contains  a  full  description  of  the  information 
contained  in  the  message  body. 


In  this  ©xample  W6  will  see  how  a  client  can  use  the  automatic  constraint 
checking  mechanism  to  change  position.  We  will  develop  a  client  that  creates  an 
object  which  starts  to  spin  on  its  Y  axis  whenever  a  user  pointer  moves  within  its 
proximity.  The  client  simply  places  a  constraint  with  the  world  server  to  notify  the  object 
whenever  another  object  of  class  “user  pointer”  is  within  the  proximity  of  the  object. 

When  this  happens,  the  world  server  will  send  the  notification  message  to  the 
object  behavior  function  of  our  client.  The  client  will  respond  by  calling  “RotateObject” 
and  increasing  the  object’s  rotation  around  the  Y  axis. 


proxim.c 


proxim.c  ^  an  application  that  connects  to  the  server 

loads  the  object  from  file  'cube.vof'  and  ca\ 
the  object  that  it  creates  to  spin  if  a  user 
pointer  moves  within  its  proximity 


#include  <stdio.h> 

# include  <vrlib,h> 

#include  <math.h> 
tinclude  "proxim.h* 

HOBJECT  hObjl,  hLast; 

FL0AT4  rotation_y  =  0.0; 

void  RegisterShapetPCONNECTION,  HOBJECT,  char  *,  char  *); 
void  fnObjFunctionl (PCONNECTION,  HOBJECT,  PMESSAGE) ; 

/************+**************^*^^^^^^^^^^^^^^^^^^^^^^^^^^^ 
void  usage_error ( )  { 
fprintf {stderr , 

"Usage:  cube  machine\n" ) ; 

exit (1) ; 

) 

/*****  *********ir******i,^r**^,^r*^,^r^,*^,******i,***^,^,^H,^,^,^,^,^,^,^^,^ 

main tint  argc,  char  **argv)  ( 

PCONNECTION  pConnection; 
char  server_hostnameE100] ; 

PMESSAGE  pMsg; 

HCLASS  hClassl; 


•**/ 


**/ 


if (argc  <  2)  {. 
usage_error | ) ; 

} 

strcpy(server_hostname,  argvfl] ) ; 

pConnection  =  ConnectToServer(server_hostname); 
if (pConnection  ==  (PCONNECTION)  -1)  { 
fprintf (stderr, 

"Could  not  connect  to  server  on  machine  %s\n", 
server_hostname) ; 

exit(l) ; 

) 

else  { 

printf( "Connection  made  OK\n" ) ; 

} 


hClassl  a  RegisterClass (pConnection,  "TestClass" } ; 

hObjl  =  CreateObject (pConnection,  hClassl,  NULL, 
f nOb j  Func tionl , 

0,  100,  0,  0,  0,  0); 

printf ( "Sending  object  shape...\n*); 

DefineShapeFromFiie  (pConnection,  hObjl,  "VOF" ,  '•cube.vof"); 
printf("Done  sending  object  shape ... \n" ) ; 


if ( !SetupMyConstraints(pConn,  hObj) )  { 

fprintf (stderr,  "Could  not  register  constraint\n' ) ; 
exit(l); 


while (pMsg  =  ReadMessage (pConnection) )  { 
DispatchMessage (pConnection,  pMsg) ; 


DisconnectFroraServer (pConnection) 


void  fnObjFunctionl (PCONNECTION  pConn,  HOBJECT  hObj , 
PMESSAGE  pMsg)  { 

switch (pMsg->iMsgType)  { 
case  PROXIM_NOTIFY : 

RotateObject (pConn,  hOb j ,  0,  rotation_y,  0); 

rotation_y  +=  5; 

return; 

) 

DefaultServerAction (pConn,  pMsg) ; 


**/ 


_  proxlm » h 

#define  PROXIM_NOTIFY  (USER_MESSAGES  +  0) 

HCONSTRAINT  SetupMyConstraints ( PCONNECTION,  HOBJECT); 


_ constraint 8. c 

HCONSTRAINT  SetupMyCons traints ( PCONNECTION  pConn, 

HOBJECT  hObj)  { 

char  bflOOO) ; 
b[01  =  0; 

sprint f { tb [ s  trlen (b ) ] , 

"d  =  sqr  (  (current_absolute_x-other_absolute_x)  *'2  +•)  ; 
sprintf (&bfstrlen(b) ] , 

(current_absolute_y-other_absolute_j/) -"2  +"); 
sprintf {&b[strlen(b) ] , 

(current_absolute_2-other_absolute_z) ^2) " ) ; 
sprintf l&bfs trlen (b) ] , 

(d  <  100)  ScSc  (other_class  ==  %d)",  USER_POINTER); 
return (DefineConstraint (pConn,  hOb j ,  PROXIM_NOTIFY,  b) ) ; 


The  program  consists  of  two  C  files  and  a  header  file.  You  must  compile  and 
link  the  program 

%  cc  -o  proxim  proxim.c  constraints.c  -Ivr  -Ubrary_path  -linclude  oath 
and  run  it 

%  proxim  serverhostname 

^  viewer  and  an  application  that  lets  the  user  interract  with  the  VR 
world  through  a  pointer  object  of  class  USER.POINTER.  You  must  then  move  this 
pointer  in  the  proximity  of  the  cube  to  see  the  cube  spin  on  its  axis. 


Appendix  A:  Automatic  Constraint  Checking  Mechanism 

The  automatic  constraint  mechanism  is  a  feature  of  the  world  server  that  allows 
clients  to  register  constraints  which  are  checked  by  the  server  every  time  a  change 
occurs  in  the  world.  When  a  constraint  is  satisfied,  the  object  associated  with  that 
constraint  is  sent  the  notification  message  whose  value  is  associated  with  the 
constraint. 

In  order  to  register  the  constraint,  a  client  must  call  the  function 
“DefineConstraint.”  The  three  important  arguments  passed  to  the  function  are 

1  Handle  of  object  that  places  the  constraint  and  that  should  be  notified  when  the 
constraint  is  satisfied. 

2  Value  of  the  notification  message  that  will  be  sent  to  the  object’s  behavior  function. 

This  value  must  be  greater  than  or  equal  to  the  value  of  USER_MESSAGES. 

3  A  pointer  to  a  string  containing  the  constraint  specifications  as  ASCII  text. 

The  body  of  the  constraint  specification  consists  of  ASCII  text,  the  grammar  of 
the  language  is  shown  here: 


language 

statainent_list 

statament 


statament_list  condition_list 
condition_list 
statament_list  statament 
statament 

VARIABLE  =  expression 


expression 


function 


condition_list 

condition 


function  (  expression  ) 
function2  <  ) 
expression  +  expression 
expression  -  expression 
expression  *  expression 
expression  /  expression 
expression  ^  expression 
-  expression 
(  expression  ) 

VARIABLE 

mMBER 

expression  | |  expression 
expression  &&  expression 
expression  ««  expression 
expression  !«  expression 
expression  >=  expression 
expression  >  expression 
expression  <«  expression 
I  expression  <  expression 
cos 
I  sin 
I  acos 
I  asin 

I 

I  log 
I  abs 
I  sqr 

condition_list  condition 
I  condition 
@  expression 


function2 


VARIABLE 


shape_change_in_other 
I  created^other 
I  destroyed_othQr 

any  legal  C  variable  name 


NUMBER 


any  integer  or  floating  point  number 


Bold  letters  indicate  actual  characters  while  normal  letters  indicate  expansions. 

The  constraint  specifications  are  interms  of  two  objects:  The  first  object  is  the 
one  that  is  registering  the  constraint  and  is  called  the  “current  object”  while  the  second 
is  any  generic  object  and  is  called  the  “other  object.”  The  constraint  specifications  can 
be  constructed  out  of  predefined  variables  which  are  assigned  numeric  values 
corresponding  with  the  characteristics  of  the  objects  being  checked.  Table  A1  lists  all 
of  these  predefined  variables. 


Generic  Object 


other_object 
other_class 
o  t  he  r e 1 a  t i ve_x 
other_relative_y 
other__relative_z 
o t he r_o 1 d_r e 1 a t i ve_x 
other_old_relative_y 
other_old_relative_z 
other_absolute_x 
other_absolute_y 
other_absolute_z 
other_old_absolute_x 
other_old_absolute_y 
other_old_absolute_z 
other_rotation_x 
other_rotation_y 
other_rotation_z 
other_old_rotation_x 
other_old_rotation_y 
other_old_rotation_z 
other_scaling_x 
other_scalinq  v 
o  t he  r_s  cal ing_z 
other^old^scaling_x 
other_old_scalinq  v 
other_old_scaling_z 
other_f ront_x 
other_front_y 
other_front_z 
other_old_front_x 
o  t  her_o 1 d_  f r on t_y 
other_old_front_z 
other_up_x 
other_up_y 
other_up_z 
other_old__up_x 
o  t he  r_o 1 d_up_y 
other_old_up_2 
other_right_x 
o  t her_r igh  t_y 
other_right_z 
other_old_right„x 
other_old_right_y 
other_old_right_z 


Current  Object 


current 

current 

current 

current 

current 

current 

current 

current 

current 

current 

current 

current 

current 

current 

current 

current 

current 

current 

current 

current 

current 

current 

current 

current. 

current. 

current. 

current. 

current. 

current. 

current. 

current. 

current. 

current. 

current 

current 

current 

current 

current 

current 

current 

current 

current. 

current. 

current. 


:_object 
,class 

:_relative_x 
:_relative_y 
:_relative_2 
:_old_relative_x 
.old_relative_y 
.old„relative_2 
.absolute_x 
.absolute_y 
.absolute_z 
.old_absolute_x 
.old_absolute_y 
.old_absolute_z 
.rotation_x 
_rotation_y 
_rotation_2 
_old_rotation_x 
_old_rotation_y 
_old_rotation_z 
_scaling_x 
_scaling_y 
_sca linger 
_old_scaling_x 
_old_scaling_y 
_old_scaling_2 
_front_x 
.front_y 
_front_z 
_old_front_x 
_old_front_y 
_old_front_z 
.up_x 
-up^ 

.up_z 

.old_up_x 

.old_up_y 

.old_up_z 

.right_x 

.right_y 

.right_z 

.old_right„x 

.old_,right_y 

.old_right_2 


Interpretation  of  Field’s  Value 


handle  number 
class  number 

coordinates  ralative  to  parrent  before  object  is  transformed  to  world  coordinate  system 
old  relative  coordinates  before  last  change 

coordinates  in  world  coordinates  after  object  is  transformed  to  world  coordinate  system 
absolute  coordinates  before  last  change  (may  be  used  to  calculate  velocity) 
rotation  around  the  axes  in  parent’s  coordinate  system 

rotation  around  axes  before  last  change  (may  be  used  to  calculate  angular  velocity) 
scaling 

old  scaling  (may  be  used  to  calculate  scaling  velocity) 

unit  vector  that  points  along  the  positive  z  axis  in  parent  coordinate  system  before  rotation 
may  point  in  a  different  location  after  rotation 

front  vector  before  last  change 


unit  vector  that  points  along  the  positive  y  axis  In  parent  coordinate  system  before  rotation 
may  point  in  a  different  location  after  rotation 

up  vector  before  last  change 

unit  vector  that  points  along  the  positive  x  axis  in  parent  coordinate  system  before  rotation 
may  point  in  a  different  location  after  rotation 


right  vector  before  last  change 


Table  A1 

The  constraint  specification  language  contains  pre-defined  functions.  Table  A2 
lists  all  these  functions. 


cos 

sin 

acos 


exp 

log 


sqr 

shape_change_in_other ( ) 
created_other ( ) 
des  troyed_o ther { ) 


Parapeter 


radians  angle 
radians  angle 
ratio 

ratio 

float 
float 
float 
float 
none 
none 
none 


Description 


returns  the  cosine  of  the  given  angle 
returns  the  sine  of  the  given  angle 

calculates  the  inverse  cosine  function  of  the  given  number  and  returns  the 
angle  in  radians 

calculates  the  inverse  sine  function  of  the  given  number  and  returns  the  anqie 
in  radians 

raises  the  natural  constant  e  to  the  given  number 
calculate  sthe  natural  logarithm  of  the  given  number 
returns  the  absolute  value  of  the  given  number 
returns  the  square  root  of  the  given  number 

returns  1  if  the  other  (generic  object  has  changed  shape),  else  returns  0 
returns  1  if  the  other  object  was  just  created,  elsd  returns  0 
returns  1  if  the  other  object  was  just  destroyed.  eiW  returns  0 


Table  A2 


When  the  world  server  checks  a  constraint  and  determines  that  the  constraint 
placed  by  an  object  has  been  met  by  some  other  generic  object,  the  first  object  is  sent 
a  notification  message  with  the  message  value  equal  to  that  specified  when  the 
constraint  was  placed  and  the  message  mody  containing  various  information  about  the 
other  (generic)  object  that  satisfied  the  constraint.  This  information  is  shown  in  Table 
A3. 


Byte 

Position 

Format  (Big  Endian) 

Description 

0 

4  byte  integer 

handle  of  other  object 

4 

4  byte  integer 

handle  of  other  object’s  parent  (NULL  if  no  parent) 

8 

4  byte  integer 

class  of  other  object 

12 

4  byte  floating  point  number 

absolute  x  of  other  object 

16 

4  byte  floating  point  number 

absolute  y  of  other  object 

20 

4  byte  floating  point  number 

absolute  z  of  other  object 

24 

4  byte  floating  point  number 

X  component  of  front  pointing  vector  in  other  object 

28 

4  byte  floating  point  number 

y  component  of  front  pointing  vector  in  other  object 

32 

4  byte  floating  point  number 

2  component  of  front  pointing  vector  in  other  object 

36 

4  byte  floating  point  number 

X  component  of  up  pointing  vector  in  other  object 

40 

4  byte  floating  point  number 

y  component  of  up  pointing  vector  in  other  object 

44 

4  byte  floating  point  number 

2  component  of  up  pointing  vector  in  other  object 

48 

4  byte  floating  point  number 

X  component  of  right  pointing  vector  In  other  object 

52 

4  byte  floating  point  number 

y  component  of  right  pointing  vector  in  other  object 

56 

4  byte  floating  point  number 

2  component  of  right  pointing  vector  in  other  object 

60 

4  byte  floating  point  number 

relative  x  coordinate  of  other  object 

64 

4  byte  floating  point  number 

relative  y  coordinate  of  other  object 

68 

4  byte  floating  point  number 

relative  z  coordinate  of  other  object 

72 

4  byte  floating  point  number 

rotation  around  the  x  axis  of  other  object 

76 

4  byte  floating  point  number 

rotation  around  the  y  axis  of  other  object 

80 

4  byte  floating  point  number 

rotation  around  the  z  axis  of  other  object 

84 

4  byte  floating  point  number 

scaling  in  the  x  direction  of  other  object 

88 

4  byte  floating  point  number 

scaling  in  the  y  direction  of  other  object 

92 

4  byte  fioatinq  point  number 

scaling  in  the  z  direction  of  other  object 

Table  A3 


This  information  can  be  extracted  from  the  message  by  calling 
“ExtractNetworkData”  whose  functionality  is  similar  to  that  of  “sscanf.”  By  using  this 
function,  the  data  can  be  converted  to  the  format  of  the  machine  on  which  the  client  is 
running  (from  Big  Endian  to  Little  Endian  perhaps). 


mocanuv@soIix.fiu.edu 


ReadMessage 


Summary 

Blocking 

PMESSAGE  ReadMessage(pConnection); 
PCONNECTION  pConnection; 


Description 

ReadMessage  fetches  the  first  message  in  the  message  queue  and  returns  a  pointer  to  the  MESSAGE 
structure.  If  no  messages  are  present  in  the  message  queue  associated  with  this  connection,  ReadMessage 
will  block  until  a  complete  message  arrives  on  the  connection. 

ReadMessage  decodes  all  the  fields  except  the  data  field  in  the  MESSAGE  structure  from  network 
format  to  machine  format.  The  information  in  the  data  field  of  the  MESSAGE  structure  can  be  extracted 
by  calling  the  ExtractNetworkData  function. 

ReadMessage  is  normally  used  in  conjunction  with  DispatchMessage. 


Return  Value 

ReadMessage  returns  a  pointer  to  a  MESSAGE  structure. 


See  Also 

DispatchMessage,  CreateObject 


DispatchMessage 


Summary 

Blocking 

void  DispatchMessage(pConnection,  pMessage); 
PCONNECTION  pConnection; 
PMESSAGE  pMessage; 


Description 

DispatchMessage  takes  a  pointer  to  a  MESSAGE  structure  (usually  returned  by  ReadMessage)  and 
dispatches  it  to  the  function  that  implements  the  behavior  of  an  object. 

DispatchMessage  accomplishes  this  as  follows: 

DispatchMessage  first  looks  at  the  destination  object  handle  inside  the  MESSAGE  structure  and 
then  calls  the  appropriate  function  that  was  associated  with  that  object  when  the  CreateObject 
function  was  called. 


Return  Value 

None. 


See  Also 

ReadMessage,  CreateObject 


DefauItServerAction 


Summary 

Non-Blocking 

void  DefaultServerAction(pConnection,  pMessage); 
PCONNECTION  pConnection; 

PMESSAGE  pMessage; 


Description 

DefauItServerAction  sends  the  message  pointed  to  by  pMessage  to  the  World  Server  on  the  connection 
pointed  to  by  pConnection. 

DefauItServerAction  is  usually  called  from  within  a  function  that  implements  the  behavior  of  an  object. 
Normally,  this  function  is  first  called  by  DispatchMessage.  The  function  then  looks  at  the  message  and 
takes  appropriate  action(s).  The  function  then  calls  DefauItServerAction  right  before  exiting. 

When  the  World  Server  receives  the  message,  the  World  Server  takes  an  appropriate  default  action  in 
response  to  the  message.  For  example,  if  the  message  DESTROY_OBJECT  is  received  by  the  object 
function,  the  function  can  first  take  appropriate  action  and  then  call  DefauItServerAction  which  sends 
the  message  to  the  World  Server  and  takes  the  default  action  of  removing  this  object  from  its  database. 


Return  Value 

None. 


See  Also 


CreateObjeCt,  DispatchMessage,  ReadMessage 


SendMessage 


Summary 

Non-Blocking 

void  SendMessage(pConnection,  iMsgType,  iNetTrips,  hDestObject,  sData,  iSize); 
PCONNECTION  pConnection; 

INT4  iMsgType; 

INT4  iNetTrips; 

HOBJECT  hDestObject; 

void  *sData; 

INT4  iSize; 


Description 

SendMessage  creates  a  MESSAGE  structure  and  sends  it  out  to  the  network.  SendMessage  encodes  for 
network  transmission  all  the  fields  in  the  MESSAGE  structure  except  for  the  message  data.  The  message 
information  must  be  encoded  into  a  buffer  by  calling  FormatNetworkData  function,  before  calling 
SendMessage. 

The  parameters  of  this  function  are: 


pConnection 

PCONNECTION 

This  is  a  pointer  to  a  CONNECTION  data  structure 
returned  by  ConnectToServer. 

iMsgType 

INT4 

This  is  a  number  identifying  the  message  to  be  sent.  i.e. 
DESTROY_OBJECT. 

iNetTrips 

INT4 

This  is  the  number  of  times  a  message  has  been  passed 
between  a  Client  and  the  World  Server.  When  calling 
SendMessage,  this  number  should  normally  be  1. 

hDestObject 

HOBJECT 

This  is  the  handle  of  the  object  to  which  the  message 
should  be  sent. 

sData 

void  * 

This  is  a  pointer  to  a  buffer  containing  the  data  of  the 
message  in  network  format.  The  data  can  be  encoded 
from  machine  format  to  network  format  by  calling  the 
function  FormatNetworkData. 

iSize 

INT4 

This  is  the  size  of  the  data  in  the  buffer. 

Return  Value 
None. 


See  Also 


ConnectToServer,  ExtractNetworkData,  FormatNetworkData 


F  ormatNetworkData 


Summary 

Non-Blocking 

int  FormatNetworkData(sFormat,  sBuffer,  paraml,  param2,  param3, ....  paramN); 


char 

*sFormat; 

void 

*sBuffer; 

void 

*paraml; 

void 

*param2; 

void 

*param3; 

void 

*paramN; 

Description 


FormatNetworkData  encodes  values  from  machine  format  to  network  (machine  independent)  format 
which  may  be  sent  to  the  World  Server  by  calling  the  SendMessage  function. 

The  parameters  of  this  function  are: 


sFormat  char  * 


sBuffer 

void 

paraml 

void 

param2 

void 

param3 

void 

paramN 

void 

This  is  a  pointer  a  character  string  that  specifies  what  data  must  be 
converted  to  network  format.  The  string  contains  a  series  of  tokens 
separated  by  spaces  with  the  following  meaning: 

11  data  of  size  1  such  as  INTI  or  char 

12  data  of  size  2  such  as  INT2 

i4  data  of  size  4  such  as  INT4  or  HOBJECT 

f4  floating  point  value  of  size  4  such  as  FLOAT4 

f8  floating  point  value  of  size  8  such  as  FLOATS 

sN  string  of  characters  of  size  N 
Each  of  these  tokens  corresponds  to  one  of  the  values  pointed  to  by 
paraml  through  paramN  to  be  converted  from  machine  format  to 
network  format. 

This  is  the  are  of  memory  where  the  formatted  data  should  be  stored. 
This  argument  is  later  passed  to  SendMessage. 

Pointer  to  first  parameter  to  be  converted. 

Pointer  second  parameter  to  be  converted. 

Pointer  to  third  parameter  to  be  converted. 

Pointer  to  Nth  parameter  to  be  converted. 


Return  Value 

Number  of  parameters  successfully  converted. 


See  Also 


ExtractNetworkData,  SendMessage 


ExtractNetworkData 


Summary 

Non-Blocking 

int  ExtractNetworkData(sFormat,  sBuffer,  paraml,  param2,  param3, paramN); 


char 

*sFormat; 

void 

*sBuffer; 

void 

*paraml; 

void 

*param2; 

void 

*param3; 

void 

*paramN; 

Description 

ExtractNetworkData  decodes  values  from  network  (machine  independent)  format  to  machine  format 
which  may  be  used  by  the  application.  This  function  is  normally  called  when  handling  a  message  that  is 
received  by  the  function  implementing  the  behavior  of  an  object. 

The  parameters  of  this  function  are: 

sFormat  char  *  This  is  a  pointer  to  a  character  string  that  specifies  what  data  must  be 

converted  to  machine  format.  The  string  contains  a  series  of  tokens 
separated  by  spaces  with  the  following  meaning: 

11  data  of  size  1  such  as  INTI  or  char 

12  data  of  size  2  such  as  INT2 

i4  data  of  size  4  such  as  INT4  or  HOB  JECT 

f4  floating  point  value  of  size  4  such  as  FLOAT4 

f8  floating  point  value  of  size  8  such  as  FLOATS 

sA^  string  of  characters  of  size  N 
Each  of  these  tokens  corresponds  to  one  of  the  memory  locations 
pointed  to  by  paraml  through  paramN  into  which  network 
formatted  data  pointed  to  by  sBuffer  is  to  be  converted  to  machine 
format. 


sBuffer 

void  * 

This  is  the  are  of  memory  where  the  formatted  data  should  be  stored. 
This  argument  is  later  passed  to  SendMessage. 

paraml 

void  * 

Pointer  to  memory  location  into  which  first  data  item  is  to  be  placed 
after  being  converted  from  network  format  to  machine  format. 

param2 

void  * 

Pointer  to  memory  location  into  which  second  data  item  is  to  be 
placed  after  being  converted  from  network  format  to  machine  format. 

param3 

void  * 

Pointer  to  memory  location  into  which  third  data  item  is  to  be  placed 
after  being  converted  from  network  format  to  machine  format. 

paramN 

void  * 

Pointer  to  memory  location  into  which  Nth  data  item  is  to  be  placed 
after  being  converted  from  network  format  to  machine  format. 

Return  Value 


Number  of  parameters  successfully  converted. 


See  Also 


FormatNetworkData,  SendMessage 


CreateObject 


Summary 

Blocking 

HOBJECT  CreateObject(pConnection,  hClass,  hParentObj,  pFunction); 
PCONNECTION  pConnection; 

HCLASS  hClass; 

HOBJECT  hParentObj; 

PEN  pFunction; 


Description 

CreateObject  sends  a  message  to  the  World  Server  requesting  that  a  new  object  be  created.  This  function 
blocks  and  waits  for  an  acknowledgment  from  the  World  Server.  The  acknowledgment  contains  the 
handle  of  the  new  object  which  is  returned  to  the  caller  if  the  function  if  successful.  If  the  function  fails, 
CreateObject  returns  NULL. 

The  parameters  of  this  function  are: 


pConnection 

PCONNECTION 

This  is  a  pointer  to  a  CONNECTION  structure  returned 
by  ConnectToServer. 

hClass 

HCLASS 

This  is  the  handle  to  a  class  returned  by  RegisterClass, 
GetClass,  or  GetObjectClass. 

hParentObj 

HOBJECT 

This  is  the  handle  of  the  object  of  whom  the  current  object 
wants  to  be  a  child.  If  the  current  object  needs  to  be  a  top 
level  object,  this  parameter  is  NULL. 

pFunction 

PEN 

Pointer  to  a  function  implementing  the  behavior  of  this 
object.  CreateObject  associates  this  function  with  this 
object  handle  so  that  DispatchMessage  calls  this  function 
if  the  destination  object  handle  in  a  message  is  equal  to 
the  object  handle  of  this  object. 

Return  Value 

Handle  of  new  object  is  success.  NULL  if  failure. 


See  Also 

ConnectToServer,  GetClass,  GetObjectClass,  DispatchMessage,  RegisterClass 


DestroyObject 


Summary 

Non-Blocking 

HOBJECT  DestroyObject(pConnection,  hObject); 
PCONNECTION  pConnection; 

HOBJECT  hObject; 


Description 

DestroyObject  sends  a  DESTROY_OBJECT  message  to  the  object  specified  by  hObject  through  the 

World  Server. 

The  parameters  of  this  function  are: 

pConnection  PCONNECTION  This  is  a  pointer  to  a  CONNECTION  structure  returned 

by  ConnectToServer. 

hObject  HOBJECT  This  is  the  handle  of  the  object  that  will  receive  the 

DESTROY_OBJECT  message.  That  object  will  only  be 
destroyed  if  it  calls  DefaultServer Action  with  the 
DESTROY_OB  JECT  message. 


Return  Value 

None. 


See  Also 


ConnectToServer,  DefaultServerAction,  SendMessage 


RegisterClass 


Summary 

Blocking 

HCLASS  RegisterClass(pConnection,  sClassName); 
PCONNECTION  pConnection; 
char  *sClassName; 


Description 

RegisterClass  requests  that  a  new  class  with  the  name  specified  in  sClassName  be  created  in  the  server. 
If  a  class  by  that  name  already  exists,  the  server  sends  back  the  handle  of  the  class.  If  the  class  does  not 
exist,  then  a  new  class  is  created  with  the  name  specified  in  sClassName  and  a  new  handle  is  assigned  to 
it  which  is  returned  to  the  caller. 


The  maximum  number  of  classes  that  a  client  can  register  is  MAX_CLASSES_PER_CLIENT. 

Two  classes  are  predefined  in  the  server.  They  are: 

“ObservationPointClass”  with  a  handle  value  of  1 

“UserPointerClass”  with  a  handle  value  of  2 


The  parameters  of  this  function  are: 


pConnection 

sClassName 


PCONNECTION  This  is  a  pointer  to  a  CONNECTION  structure  returned 
by  ConnectToServer. 

char  *  This  is  a  pointer  to  a  string  of  characters  containing  the 
name  of  the  class  to  register  with  the  server. 


Return  Value 

Handle  of  class.  NULL  if  failure. 


See  Also 

ConnectToServer,  GetClass,  GetObjectClass 


GetClass 


Summary 


Blocking 

HCLASS  GetClass(pConnection,  sClassName); 
PCONNECTION  pConnection; 
char  *sClassName; 


Description 

GetClass  requests  the  handle  of  the  class  with  the  name  specified  in  sClassName. 

Two  classes  are  predefined  in  the  server.  They  are: 

“ObservationPointCIass”  with  a  handle  value  of  1 

“UserPointerClass”  with  a  handle  value  of  2 

The  parameters  of  this  function  are: 

pConnection  PCONNECTION  This  is  a  pointer  to  a  CONNECTION  structure  returned 

by  ConnectToServer. 

sClassName  char  *  This  is  a  pointer  to  a  string  of  characters  containing  the 

name  of  the  class  to  get  handle  for. 


Return  Value 

Handle  of  class.  NULL  if  failure. 


See  Also 

ConnectToServer,  GetObjectClass,  RegisterClass 


GetCIass 


Summary 


Blocking 


HCLASS  GetClass(pConnection,  sClassName)- 
PCONNECTION  pConnection; 

*sClassName; 


Description 


GetCte  requests  the  handle  of  the  class  with  the  name  specified  in  sCIassName. 

Two  classes  are  predefined  in  the  server.  They  are: 

“ObservationPointClass”  with  a  handle  value  of  1 

UserPointerClass”  with  a  handle  value  of  2 

The  parameters  of  this  function  are: 


pConnection 

sClassName 


PCONNECTION 


is  a  pointer  to  a  CONNECTION  structure  returned 
by  ConnectToServer. 

char  This  is  a  pointer  to  a  string  of  characters  containing  the 
name  of  the  class  to  get  handle  for. 


Return  Value 

Handle  of  class,  NULL  if  failure. 


See  Also 


ConnectToServer,  GetObjectClass,  RegisterClass 


GetObjectClass 


Summary 

Blocking 

HCLASS  GetObjectClass(pConnection,  hObject)- 
PCONNECTION  pConnection; 

HOBJECT  hObject; 


Description 

GetObjectClass  requests  the  class  handle  of  an  object  specified  in  hObject. 

The  parameters  of  this  function  are: 

pConnection  PCONNECTION  This  is  a  pointer  to  a  CONNECTION  structure  returned 

by  ConnectToServer. 

hObject  HOBJECT  This  is  the  object  handle  for  whom  the  class  handle  is 

requested. 


Return  Value 

Class  handle  of  the  object  specified  in  hObject.  NULL  if  failure. 


See  Also 


ConnectToServer,  GetClass,  RegisterClass 


DeflneConstraint 


Summary 

Blocking 

HCONSTRAINT  DefineConstraint(pConnection,  hObject,  iMsgType  sText)- 
PCONNECTION  pConnection; 

HOBJECT  hObject; 

INT4  iMsgType; 

char  *sText; 


Description 

DeflneConstraint  sends  to  the  World  Server  some  text  specifying  the  circumstances  under  which  an 
object  should  be  notified  by  the  World  Server.  The  notification  is  in  the  form  of  a  message  of  type 
iMsgType  that  is  sent  from  the  World  Server  to  the  object  whose  handle  is  given  in  hObject. 

The  parameters  of  this  function  are: 


pConnection 

PCONNECTION 

This  is  a  pointer  to  a  CONNECTION  structure  returned 
by  ConnectToServer. 

hObject 

HOBJECT 

Handle  of  the  object  that  should  be  notified  if  the 
constraint  is  met. 

iMsgType 

INT4 

The  value  of  the  message  that  will  be  sent  to  the  object  if 
the  constraint  is  met. 

sText 

char  * 

This  points  to  a  buffer  containing  the  text  that  defines  the 
constraint.  For  the  exact  syntax  see  the  User^s  Guide. 

Return  Value 

Handle  of  the  newly  created  constraint  in  the  server.  NULL  if  failure. 


See  Also 


ConnectToServer,  CreateObject,  DestroyConstraint 


DestroyConstraint 


Summary 

Blocking 

void  DestroyConstraint(pConnection,  hObject,  hConstraint); 
PCONNECTION  pConnection; 

HOBJECT  hObject; 

HCONSTRAINT  hConstraint; 


Description 

DestroyConstraint  sends  a  DESTROY_CONSTRAINT  message  to  the  object  whose  handle  is  in 
hObject.  Upon  receipt,  the  object  may  call  DefaultServerAction  with  the  DESTROY_CONSTRAINT 
message  which  will  then  cause  the  World  Server  to  remove  the  constraint  from  the  object’s  list  of 
constraints  that  define  when  that  object  should  be  sent  a  notification  message. 

The  object  whose  handle  is  specified  in  hObject  must  have  first  registered  a  constraint  with  the  server  by 
calling  DefineConstraint. 

The  parameters  of  this  function  are: 

pConnection  PCONNECTION  This  is  a  pointer  to  a  CONNECTION  structure  returned 

by  ConnectToServer. 

hObject  HOBJECT  Handle  of  the  object  that  owns  the  constraint. 

hConstraint  HCONSTRAINT  The  handle  of  the  constraint  registered  by  the  object  in 

hObject  with  DefineConstraint. 


Return  Value 

Handle  of  the  newly  created  constraint  in  the  server.  NULL  if  failure. 


See  Also 


ConnectToServer,  CreateObject,  DestroyConstraint 


Summary 

Non-Blocking 

void  MoveObject(pConnection,  hObject,  relative_x,  relative_y,  relative_z)- 
PCONNECTION  pConnection; 

HOBJECT  hObject; 

FLOAT4  relative_x,  relative_y,  relative_z; 


Description 

MoveObject  sends  a  MOVE_OBJECT  message  to  the  object  whose  handle  is  in  hObject.  Upon  receipt, 
the  object  may  call  DefaultServerAction  which  will  then  cause  the  World  Server  to  change  the  object’s  ’ 
(x,  y,  z)  relative  coordinates  in  the  database. 

The  (x,  y,  z)  coordinates  are  relative  to  the  origin  of  the  parent  object.  If  the  object  is  a  top  level  object 
then  the  (x,  y,  z)  coordinates  represent  relative  coordinates  with  respect  to  the  world’s  origin. 

The  absolute  coordinates  of  the  object  are  calculated  as  a  function  of  this  object’s  (x,  y,  z)  coordinates,  (x, 
y,  z)  rotation,  as  well  as  the  parent’s  rotation.  The  World  Server  keeps  a  hierarchical  structure  of  objects. 
In  order  to  calculate  the  absolute  coordinates  of  an  object,  the  world  server  starts  by  translating  and 
rotating  first  the  leaves  of  the  object  tree  and  moves  up  the  tree  to  the  root  constantly  applying  the 
translate/rotate  process.  (This  is  not  the  actual  algorithm  however). 

A  single  object  is  first  translated  to  its  relative  (x,  y,  z)  coordinates  which  the  function  MoveObject 
modifies  and  then  the  object  is  rotated  around  the  Z  axis,  followed  by  a  rotation  around  the  X  axis 
followed  by  a  rotation  around  the  Y  axis  by  the  (x,  y,  z)  rotation  values  which  the  function  RotateObject 
modifies.  The  absolute  coordinates  of  all  the  children  of  this  object  are  subsequently  modified. 


Return  Value 
None. 


See  Also 

RotateObject,  MoveRotateObject 


RotateObject 


Summary 

Non-Blocking 

void  RotateObject(pConnection,  hObject,  rotatlon^x,  rotationv,  rotation  z)- 
PCONNECTION  pConnection;  ~  ’ 

HOBJECT  hObject; 

rLOAT4  rotation_x,  rotation_y,  rotation_z; 


Description 


RotateObject  sends  a  ROTATE_OBJECT  message  to  the  object  whose  handle  is  in  hObject.  Upon 
receipt,  the  object  may  call  DefaultServerAction  with  the  message  which  will  then  cause  the  World 
Server  to  change  the  object’s  (x,  y,  z)  rotations  in  the  database. 

The  object’s  absolute  coordinates  are  calculated  as  a  function  of  the  object’s  (x,  y,  z)  rotation  which  this 
function  modifies  and  (x,  y,  z)  coordinates. 


The  absolute  coordinates  of  the  object  are  calculated  as  a  function  of  this  object’s  (x,  y,  z)  coordinates  fx 
y,  z)  rotation,  as  well  as  the  parent’s  rotation.  The  World  Server  keeps  a  hierarchical  structure  of  objects' 
In  order  to  calculate  the  absolute  coordinates  of  an  object,  the  world  server  starts  by  translating  and 
rotating  first  the  leaves  of  the  object  tree  and  moves  up  the  tree  to  the  root  constantly  applying  the 
translate/rotate  process.  (This  is  not  the  actual  algorithm  however). 

A  single  object  is  first  translated  to  its  relative  (x.  y,  z)  coordinates  which  the  function  MoveObject 
modifies  and  then  the  object  is  rotated  around  the  Z  axis,  followed  by  a  rotation  around  the  X  axis 

modifi^  "TT'!  ®  y-  z)  rotation  values  which  the  function  RotateObject 

odifies.  The  absolute  coordinates  of  all  the  children  of  this  object  are  subsequently  modified. 


Return  Value 

None, 


See  Also 


MoveObject,  MoveRotateObject 


MoveRotateObject 


Summary 

Non-Blocking 

void  MoveRotateObject(pConnection,  hObject,  relative_x.  relative_y,  relative_z,  rotation_x,  rotation_y, 
rotation_z); 

PCONNECTION  pConnection; 

HOBJECT  hObject; 

FLOAT4  relative_x,  relative_y,  relative_z; 

FLOAT4  rotation_x,  rotation_y,  rotation_z; 


Description 


MoveRotateObject  sends  a  MOVE_ROTATE_OBJECT  message  to  the  object  whose  handle  is  in 
hObject.  Upon  receipt,  the  object  may  call  DefaultServerAction  with  the  message  which  will  then  cause 
the  World  Server  to  change  the  object’s  (x,  y,  z)  relative  coordinates  and  (x,  y,  z)  rotations  in  the  database. 

The  object’s  absolute  coordinates  are  calculated  as  a  function  of  the  object’s  (x,  y,  z)  rotation  which  this 
function  modifies  and  (x,  y,  z)  coordinates. 


The  absolute  coordinates  of  the  object  are  calculated  as  a  function  of  this  object’s  (x,  y,  z)  coordinates  (x 
y.  z)  rotation  as  well  as  the  parent’s  rotation.  The  World  Server  keeps  a  hierarchical  structure  of  objects’, 
n  order  to  calculate  the  absolute  coordinates  of  an  object,  the  world  server  starts  by  translating  and 
rotating  first  the  leaves  of  the  object  tree  and  moves  up  the  tree  to  the  root  constantly  applying  the 
translate/rotate  process.  (This  is  not  the  actual  algorithm  however). 

A  single  object  is  first  translated  to  its  relative  (x,  y,  z)  coordinates  which  the  function  MoveObiect 
modifies  and  then  the  object  is  rotated  around  the  Z  axis,  followed  by  a  rotation  around  the  X  axis 
followed  by  a  rotation  around  the  Y  axis  by  the  (x,  y,  z)  rotation  values  which  the  function  RotateObject 
modifies.  The  absolute  coordinates  of  all  the  children  of  this  object  are  subsequently  modified 


Return  Value 


None. 


See  Also 

MoveObject,  RotateObject 


SetTimer 


Summary 

Non-Blocking 

void  SetTimer(pConnection,  hObject,  milliseconds,  seconds); 
PCONNECTION  pConnection; 

HOBJECT  hObject; 

long  milliseconds,  seconds; 


Description 

This  function  does  not  send  any  messages  to  the  server  but  simply  sets  up  a  periodic  timer  interrupt  that 
will  periodically  call  the  message  handling  function  for  the  object  specified  by  hObject  with  a  TIMER 
message.  The  periodic  function  call  is  a  direct  call.  The  message  is  not  placed  in  the  message  queue  like 
all  other  messages  arriving  at  the  message  handling  function. 

The  values  in  milliseconds  and  seconds  determine  the  rate  of  the  periodic  callback.  The  interval  between 
to  consecutive  callbacks  is  given  by  adding  the  two  values  together. 

Only  one  timer  can  be  set  per  application. 


Return  Value 

None. 


See  Also 


CreateObject,  StopTimer 


StopTimer 


Summary 

Non-Blocking 
void  StopTimer(void); 


Description 

This  function  disables  the  automatic  periodic  callback  mechanism  established  with  the  SetTimer  function 
call. 


Return  Value 

None. 


See  Also 


SetTimer 


DefineShape 


Summary 

Blocking 

int  DefineShape(pConnection,  hObject,  sName,  sFormat); 
PCONNECTION  pConnection; 

HOBJECT  hObject; 

char  *sName; 

char  *sFormat; 


Description 

This  function  creates  a  format  for  the  object  identified  by  hObject.  sName  is  a  pointer  to  a  string 
containing  the  name  of  the  format  you  want  to  register.  sFormat  is  a  pointer  to  memory  containing  the 
text  of  the  format  itself. 

The  format  body  must  be  some  zero-terminated  ASCII  text.  Future  versions  of  the  system  may  allow  the 
application  to  specify  a  format  that  is  not  necessarily  ASCII. 

The  format  of  an  object  describes  the  3D  shape  of  that  object.  Examples  of  such  descriptions  are  the  DXF 
format,  VOF  format,  NFF  format,  etc.  The  format  of  an  object  is  uploaded  to  the  world  server  by  the 

application.  Any  viewer  wishing  to  display  the  object  must  download  this  format  by  calling  the  GetShane 
function. 

Upon  return,  memory  that  may  have  been  allocated  and  pointed  to  by  sName  or  sFormat  can  be 
deallocated. 


Return  Value 

Returns  a  non-zero  value  if  successful.  NULL  if  error. 


See  Also 


DefineShapeFromFile,  GetShape,  GetShapeFormat 


GetShape 


Summary 


Blocking 


char  *GetShape(pConnection,  hObject.  sName,  sFormat)- 
PCONNECTION  pConnection; 

HOBJECT  hObject; 

*sFonnat; 


Description 


T^is  function  returns  a  pointer  to  memory  containing  the  format 
address  contained  in  sName  of  the  object  in  hObject. 


whose  name  is  given  by  the  string  at  the 


The  format  b^y  returned  by  this  function  is  a  zero-terminated  ASCII  string  Future  versions  of  th. 
system  may  allow  the  application  to  specify  a  format  that  is  not  necessarily  ASCII 

format,  VOFfo!Ii5  NIT  format  «c  ^Thtfomlt  of  descriptions  are  the  DXF 

application  b,  cailiogrtoS 


The  memory  returned  by  this  function  may  be  deallocated  if  no  longer  needed. 


Return  Value 


Returns  a  pointer  to  a  memory  buffer  containing 
string.  Returns  NULL  if  error. 


the  format  of  the  object 


as  a  zero-terminated  ASCII 


See  Also 


DefineShape,  DefineShapeFromFile,  GetShapeFormat 


GetShapeF  ormat* 


Summary 

Blocking 

void  *GetShapeFormat(pConnection,  hObject,  sPrevFormat,  sNextFormat); 
PCONNECTION  pConnection; 

HOBJECT  hObject; 

cbar  *sPrevFormat; 

char  *sNextFormat; 


Description 

This  function  retrieves  in  sNextFormat.  the  name  of  the  next  available  format  for  the  object  specified  by 
hObject.  The  format  must  have  been  registered  with  DefineFormat  or  DefineFormatFromFUe. 

sPrevFormat  is  a  pointer  to  a  string  containing  the  name  of  the  previously  obtained  format.  If  this  is 
NULL  or  empty,  the  first  available  format  is  returned  in  sNextFormat. 

The  format  of  an  object  describes  the  3D  shape  of  that  object.  Examples  of  such  descriptions  are  the  DXF 
format,  VOF  format,  NFF  format,  etc.  The  format  of  an  object  is  uploaded  to  the  world  server  by  the 
application  by  calling  the  function  DefineFormat. 


Return  Value 
None. 


See  Also 


DefineShape,  DefincShapeFromFile,  GetShape 


DefineShapeF  romFile* 


Summary 

Blocking 

int  DefineShapeFromFileCpConnection,  hObject,  sName,  sFName); 
PCONNECTION  pConnection; 

HOBJECT  hObject; 

char  *sName; 

char  *sFName; 


Description 

This  function  creates  a  format  for  the  object  identified  by  hObject.  sName  is  a  pointer  to  a  string 
containing  the  name  of  the  format  you  want  to  register.  sFName  is  a  pointer  to  a  string  containing  the 
name  of  the  file  containing  the  format  data. 

The  format  data  must  be  some  ASCII  text.  Future  versions  of  the  system  may  allow  the  application  to 
specify  a  format  that  is  not  necessarily  ASCII. 

The  format  of  an  object  describes  the  3D  shape  of  that  object.  Examples  of  such  descriptions  are  the  DXF 
format,  VOF  format,  NFF  format,  etc.  The  format  of  an  object  is  uploaded  to  the  world  server  by  the 
application.  Any  viewer  wishing  to  display  the  object  must  download  this  format  by  calling  the  GetShape 
function. 

Upon  return,  memory  that  may  have  been  allocated  and  pointed  to  by  sName  or  sFName  can  be 
deallocated. 


Return  Value 

Returns  a  non-zero  value  if  successful.  NULL  if  error. 


See  Also 


DefineShape,  GetShape,  GetShapeFormat 


